Review requested:

• @nodejs/loaders
• @nodejs/modules

• Calling require(‘./file.cjs’) shortcut the cjs-module-lexer pass that detects CJS exports (because WASM instantiation is async), but if we do a later import(‘./test.cjs’) dynamic import gets the expected list of exports?

I feel like we should be able to get away with not needing to know the list of named exports for a CommonJS module.

Specifically, here's the use case:

// target.cjs
exports.test = 1;

// target-reexport.cjs
module.exports = require('./target.cjs');

// middlepoint.cjs
require('./target-reexport.cjs');

// middlepoint.mjs
import { test } from './target-reexport.cjs';

// entry1.mjs
import './middlepoint.mjs';
import('./middlepoint.cjs');

// No issue, node is able to detect `test` as a named export.

// entry2.mjs
import './middlepoint.cjs';
import('./middlepoint.mjs'); // SyntaxError: Named export 'test' not found.

Meaning we'll get different results for the same file depending on the order of imports. I don't think that's acceptable, but we might get away with it as long as this is opt-in and experimental.

Well it already works in the current CJS loader; what’s the issue specifically?

import('data:text/javascript,');
^

TypeError: Invalid host defined options
    at Object.eval (eval at loadCJS (node:internal/modules/esm/translators:148:27), <anonymous>:4:1)
    at loadCJS (node:internal/modules/esm/translators:168:3)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:195:21)
    at ModuleJob.run (node:internal/modules/esm/module_job:213:25)

Node.js v21.0.0-pre

Surely in order to drop the current CJS loading code, every single use case, with no exceptions, would need to be met? The CJS system has been marked "stable" and "locked", I believe, for a very long time, and to me that means that no feature would ever be removed.

import('./middlepoint.mjs'); // SyntaxError: Named export 'test' not found.

I’m not following this. This is an ESM file importing an ESM file; I would expect it to work. Is this issue that the stack is entry1.mjs » middlepoint.mjs » target.cjs, but since target.cjs has been require‘d already it’s already in the cache, and therefore it doesn’t go through the whole module importing machinery to find its named exports? Wouldn’t the solution there to be something like marking it on initial require as a CJS import that hasn’t had the lexer run on it yet, and then when the later import happens it sees that flag and runs the lexer to add that additional metadata? Then the async wasm stuff still only happens in the esm import flow, when we need it; and not on the sync require flow when we can’t do it.

TypeError: Invalid host defined options

This just seems like something to be fixed in the code. Surely there’s some way to make this work in a unified-loader architecture since it already works in the current split loader setup.

Is this issue that the stack is entry1.mjs » middlepoint.mjs » target.cjs, but since target.cjs has been require‘d already it’s already in the cache, and therefore it doesn’t go through the whole module importing machinery to find its named exports?

That's my understanding as well.

This just seems like something to be fixed in the code

That seems obvious, where else would we fix it?

That seems obvious, where else would we fix it?

I just mean that this isn't a design question, it's just a matter of fixing a bug. As in we don't need to contemplate changing the API or anything like that.

As in, stuff like require.cache and require.resolve and so on? I assume we’d want to port as much as possible, especially stuff we see used in big popular projects.

Speaking of require.cache, we have to decide how to fill in __filename and __dirname for modules that don't come from the FS. I assume that for modules whose URL is a file: URL, we can simply use fileURLToPath, but for any other protocol, it's going to be an issue I think. require.cache keys are paths, so it's the same issue – or we could decide to use a slightly different API, e.g. using URL strings instead of paths as keys for not-file: modules.
The only place I could find where a CJS module is loaded by Node.js is for stdin eval, or --eval CLI flag, here's how it works:

$ node -p __filename
[eval]
$ node -p __dirname 
.
$ echo 'console.log({__filename,__dirname})' | node
{ __filename: '[stdin]', __dirname: '.' }

We could look at how other tools in the exosystem that hook into the CJS loader to provide virtual modules capabilities, but it seems they usually rely on also overriding the fs module so it's transparent to users, but I have a feeling that's not a goal for us.

We could look at how other tools in the exosystem that hook into the CJS loader to provide virtual modules capabilities, but it seems they usually rely on also overriding the fs module so it's transparent to users, but I have a feeling that's not a goal for us.

That's my understanding as well. Node's classic module system has always assumed that the module identifier is a filename, and this matches __filename, with the only exceptions being node's [stdin] and [eval]. There have been other non-Node.js CJS systems that used different semantics, but __filename was always a node-ism.

I think a reasonably un-surprising choice would be for __filename to be set to the module identifier (eg, data:text/javascript;...) if fileURLToPath(url) doesn't make sense. The only case I could imagine that causing issues is if we want to do something like require('https://unpkg.org/express') some day. But since ESM is already fit for that purpose, I think it'd even be fine for the CJS loader to just not accept anything except file:// urls.

edit to add:

Another idea would be to allow the loader to provide a __filename and __dirname in the context somehow. So you could have an https loader that can load cjs, and sets __filename to the url path or something. But as it stands right now, none of that is possible, so I don't think there's much risk of breaking any existing patterns.

There are 13 test failures to address:

Failed tests:
out/Release/node ./test/parallel/test-node-output-errors.mjs
out/Release/node ./test/parallel/test-runner-cli.js
out/Release/node ./test/es-module/test-esm-cjs-exports.js
out/Release/node --pending-deprecation ./test/es-module/test-esm-exports-deprecations.mjs
out/Release/node ./test/es-module/test-esm-exports.mjs
out/Release/node ./test/es-module/test-esm-imports.mjs
out/Release/node --pending-deprecation ./test/es-module/test-esm-imports-deprecations.mjs
out/Release/node ./test/es-module/test-esm-json-cache.mjs
out/Release/node --loader ./test/fixtures/es-module-loaders/hook-resolve-type.mjs ./test/es-module/test-esm-loader-resolve-type.mjs
out/Release/node ./test/es-module/test-esm-loader-hooks.mjs
out/Release/node ./test/es-module/test-esm-snapshot.mjs
out/Release/node --experimental-network-imports --dns-result-order=ipv4first ./test/es-module/test-http-imports.mjs
out/Release/node ./test/es-module/test-loaders-workers-spawned.mjs

There are probably tons of edge cases to also take into consideration – although supporting every CJS edge cases is probably not a goal for this PR, but we should at least document what's working and what's not – thankfully @isaacs has volunteered to help with writing tests for that. Any additional help would be appreciated, please consider getting involved :)

@aduh95 why is that not a goal? The CJS module loading system is the most stable one in node, which includes all the edge cases.

It's not a goal for this PR, I should have say (edited my message above). The long term plans of what to support and how is still open to discussion, the goal in this PR is to achieve a MVP.

thanks, that clarifies

@aduh95 found a few issues: https://gist.github.com/isaacs/a9aacc1efeca7d565f2f7828467d9e6e

1. The default load is not performed if you just return nextLoader(spec, context) in the load method. I'd expect that doing that would proceed to do the "normal" cjs load process, but it seems that with this change, you must return a shortcircuit from a loader for a "format":"commonjs" if a loader is present.
2. require.main is not set. That should be a reference to the module object for the first module loaded via process.argv[1].
3. Using the default resolver via return nextResolve(spec, context) works for the first main module, but raises an error for subsequent modules loaded via require().

I just started looking at this again, so not much insight as to why that's happening, but figured it might be obvious/easy to you, having spent more time in this code. I'll keep poking at it, hopefully have more useful feedback here shortly.

1. The default load is not performed

It is performed, the issue was that the new translator didn't support ArrayBuffer sources, but that's now fixed. I've also fixed the other points you mentioned, we're now at 10 test failures.

Can you please wait for a review from me before landing this? The off-thread loader change broke ESM support in APMs and we want to make sure this doesn't break CJS too.

Can you please wait for a review from me before landing this? The off-thread loader change broke ESM support in APMs and we want to make sure this doesn’t break CJS too.

Can you make a list of APIs that are necessary to preserve?

I would imagine that APMs will just be required to start using the loaders API, even for CommonJS, to preserve current functionality. We’ll probably land #46826 before this (or we can ensure that it’s released before this) which should make the upgrade path simpler for APM authors and hidden from end users; the --require apm-name or require('apm-name') calls that users are making now could call register to register hooks with the loaders API. This has the pleasant side effect (from Node’s perspective) of forcing APM vendors to catch up with Node and add full support for ESM apps.

Forcing APMs to "catch up" is going to go very badly. ESM changes way too quickly for APMs to keep up with it unless we have people full time on just that and that's not likely to happen. We're more likely to just not support those Node.js versions and push harder on increasing diagnostics_channel adoption. Most APM users are very slow to upgrade anyway.

I'm a little confused. Off-threading was over ½ a year in the making, and the design from an external perspective never changed throughout that period. Why is it a game of catch-up now, and what do you need to make that easier? (If this is a lengthy discussion, let's move it to the loaders repo).

PS We are very, very eager to know use-cases in the wild we need to consider, and we're actively collecting them. If you can detail your considerations, that would be most welcome—or, better yet, codify them in tests it make it obvious if we've broken them.

@Qard Please provide a list of CommonJS APIs that APMs rely on and we can try to preserve their functionality while getting the Loaders API to support CommonJS. But in my mind, if there’s any conflict between those goals, finishing the Loaders API takes priority. It’s just broken without full CommonJS support, and we can’t leave it in that state indefinitely just because some vendors who are profiting off of Node won’t invest in supporting Node’s newest versions. That said, I’m not trying to break anyone so if there’s any way to maintain compatibility with monkey-patching CommonJS internals or whatever techniques these tools rely on, I’m happy to continue supporting it whenever possible.

I would imagine that APMs will just be required to start using the loaders API, even for CommonJS, to preserve current functionality.

Can you clarify this point? Would this break how require work?
I don't think we can afford to break commonjs backward compat.

I agree that adding ESM to CJS should be designed as an extension to be successful, not a replacement.

Can you clarify this point?

That was just a hypothetical musing, that we don't need to debate as it's unlikely to happen at least anytime soon. The goal with this PR is to get all tests passing, which would mean we're not breaking any backward compatibility for any CommonJS APIs that are documented. My question for @Qard is whether there are any CommonJS APIs that APMs are relying on that aren't covered by tests; things like monkey patching that we don't officially support, but can try to preserve if this PR breaks them.

See: https://github.com/DataDog/dd-trace-js/blob/master/packages/dd-trace/src/ritm.js

I won't have time to get into more detail until Tuesday, but there are a bunch of underscore-prefixed methods on the Module class which need to be accessible for APMs to continue working.

My plan has been to migrate people to diagnostics_channel so module patching becomes no longer relevant, however that module patching mechanism needs to continue to work for at least the mid-term.

It's important to understand that you're dealing with big enterprises that plan things in quarters or years. If you want to break compatibility with something, especially something this heavily relied upon, you can't just go do that in a few months you generally need a year or more to migrate users and there needs to be something to migrate to before that can happen. And pre-release discussion doesn't count, there's no visibility for that unless a company has people actively engaging in that group which is generally not the case. That's why the off-thread loaders thing was so disruptive, because there was no flag to turn it off in the mid-term. Yes there was some leading work that went into it, but we don't have people actively engaging in the loaders group because we are a small team and don't have the time to be in every discussion. At most APMs the Node.js team is only a couple people and most of their time is going into delivering OKRs. I would love to have people working on Node.js core full-time, and I've been pushing for that, but that's simply not the reality, especially right now with hiring across the market being so tight.